# Xoronos software library

This repository contains an implementation of Xoron cryptography.
The software is currently not supported on Windows platforms.

## Overview

The scripts can be used to generate the following outputs:

1. The static libraries for both 128 and 256 bits implementations (xrnlib-128.a, xrnlib-256.a).

2. The dynamic libraries for both 128 and 256 bits implementations (xrnlib-128.so, xrnlib-256.so).

3. The interactive command line interface, which internally loads the two dynamic libraries (xrnlib-cli).

4. The interactive command line interface to convert Xoron files to standard files and vice-versa (xrnconv-cli)

5. Python libraries (_xrnlib128.so, xrnlib128.py, _xrnlib256.so, xrnlib256.py).

6. Both C and Python code examples (examples-128, examples-256).

7. Tests for each implemented function (tests-128, tests-256).

## User guide

### Clone the repository

The project can cloned using the following command:

```bash
git clone https://github.com/yourusername/xrn_lib.git
```

### Before running a script

All the front facing scripts can be found in the scripts directory.
All the scripts should be run from the scripts directory.

```bash
cd ./xrn_lib/scripts
```

All the scripts are written assuming "sudo" as the command for privilege escalation, and "apt" as package manager.
To change this behavior you can edit the initialize_host.sh, install_dependencies.sh, install.sh and uninstall.sh scripts, changing the privilege_escalation, install_cmd, update_cmd, and user_developer variables accordingly.

We recommend to run the following commands in order as shown below:

```bash
cd ./xrn_lib/scripts
./install_dependencies.sh
./initialize_host.sh
python compile_code.py
./install.sh
source $HOME/.local/xoronos/source.sh
```

### Install dependencies

To install the required dependencies, you can run the install_dependencies.sh script as below.

```bash
./install_dependencies.sh
```

### Initialize the host

To initialize the host operating system you can run the following command.

```bash
./initialize_host.sh
```

The script is used to extract all the archives present in the repository, to create directories ($HOME/.local/xoronos, $HOME/.local/cache/xoronos), and copy files in the host operating system.

This step is required to generate working scripts and code examples while running the following commands, after the program has been installed

```bash
xrnlib-cli --example command
xrnlib-cli --script command
```

Furthermore, this step is required to compile documentation.
We recommend each user to run the initialize_host.sh script, all the files can be removed later by running the uninstall.sh script.

## Compile code

To compile all the static and dynamic libraries for both C and Python, and all the outputs to install you can run:

```bash
python compile_code.py
```

The script will first compile a program to generate or restore secrets to be compiled in the program.
The tool is used to generate:

1. The permutation key.

2. The initial encoding parameters.

If you type "generate" and "random" for both the options when prompted, which is recommended for new users, you will see on the screen the two keys that can be used to recompile in a deterministic way the Xoronos utilities. 

The generated or restored secrets will be used to compile all the other outputs.

Programs that have different permutation keys will be by default incompatible with each other.
This behavior can be circumvented by disabling the permutation layer at run time, for example if the xrnlib-cli program is installed you can specify the --permutation-conf -no-permutation-key option to disable the permutation layer. 
Programs that have different encoding parameters will be by incompatible if the --decoding-conf -compiled-param or --encoding-conf -compiled-param options are specified.

To replicate the compilation you can chose "restore" instead of "generate" while prompted, you will than requested to write up the secret keys as they appeared on the screen.


## Installation

To install all the compiled outputs you can run the following command:

```bash
./install.sh
```

To remove all the files generated by the initialize_host.sh and install.st scripts on your system, you can run the uninstalling script as below.

```bash
./uninstall.sh
```

After the installation, all the Xoronos files can be found in the /etc/bash_completiiton.d/ /usr/lib/xoronos /usr/local/bin directories.
If you have pandoc installed you can find the Xoronos template in /usr/share/pandoc/data/templates directory.

## How to set environmental variables

To get tab auto complete for the xrnlib-cli command, to update the PYTHONPATH, LD_LIBRARY_PATH, TEXMFHOME variables you can run the following command.

```bash
source $HOME/.local/xoronos/source.sh
```

You can run the command also from the script directory as:

```bash
source ./source.sh
```

This step is important to make available shared libraries in C, and the import xrnlib256 or the import xrnlib128 instructions in python, and to compile the documentation.

To clean the environment from Xoronos paths you can run the following command: 

```bash
source $HOME/.local/xoronos/unsource.sh
```

You can run the command also from the script directory as:

```bash
source ./unsource.sh
```

## Running C code examples

To compile examples you can run the following command:

```bash
python compile_code.py examples-256
```

The compile_code.py removes all the outputs generated by previous compilations.

To get the list of examples you can run the following command.

```bash
python run.py
```

To run the first example you can run the following command.

```bash
python run.py 0
```

We provide only the 256 bits architecture for code examples. 
The code implementation for the 128 bits is identical to the provided 256 bits implementation.
The directory for all the code examples can be found in xrn_lib/code/app/examples/c/src/.

## Running Python code examples

To compile examples you can run the following command:

```bash
python compile_code.py swigpy-256
```

The compile_code.py removes all the outputs generated by previous compilations.

To get the list of examples you can run the following command.

```bash
python run.py
```

To run the first example you can run the following command.

```bash
python run.py 0
```

We provide only the 256 bits architecture for code examples. 
The code implementation for the 128 bits is identical to the provided 256 bits implementation.
The directory for all the code examples can be found in xrn_lib/code/app/examples/py/.

## Running tests

To compile tests using a 256 bits architecture you can run the following command:

```bash
python compile_code.py tests-256
```

To compile tests using a 128 bits architecture you can run the following command:

```bash
python compile_code.py tests-128
```

To run all the tests you can run:

```bash
python run.py
```

## Compile documentation

To run the documentation you should first:

1. Install the required dependencies by editing and running the install_dependencies.sh script, changing the user_developer variable to "developer".

2. Initialize the host operating system by running the initialize_host.sh script.

3. Source the source.sh script to update the TEXMFHOME global variable.

A summary for all the scripts can be found below.

```bash
cd scripts
./install_dependencies.sh
./initialize_host.sh
sources ./sources.sh
```

To compile the documentation you can run the following command.

```bash
python compile_documentation.py
```

The result of the compilation can be found in the xrn_lib/build/doc directory.

```bash
cd ../build/doc
```

## Usage

The best way to learn about the library is to use the xrnlib-cli tool.

To get the list of possible commands you can run one of the following instructions.

```bash
xrnlib-cli --help
xrnlib-cli --example
xrnlib-cli --script
```

The output of the previous three commands is a list of commands that can be run with comments.

The help command is used to get all the options and commands related to one instruction. One example can be found below.

```bash
xrnlib-cli --help encrypt-symmetric
```

The example command is used to get a working example related to one instruction.

```bash
xrnlib-cli --example encrypt-symmetric
```

The example command can be randomized as below.

```bash
xrnlib-cli --example -rnd encrypt-symmetric
```

The script command is used to generate a working script with the specified instruction included.

```bash
xrnlib-cli --scripts encrypt-symmetric
```

The scripts command can be randomized as below.

```bash
xrnlib-cli --scripts -rnd encrypt-symmetric
```

## License

The code provided in this repository is licensed under the GPL3.

## Contributing

We do not accept direct external code contributions to the project.
We are open for constructive feedback and bug reports.
The best way to report a bug is to contact us directly.

## Contact

For any question or feedback, you can contact us at support@xoronos.com
